Розширені Type Guards у TypeScript: Користувацькі функції-предикати проти валідації під час виконання

У постійно мінливому ландшафті розробки програмного забезпечення забезпечення безпеки типів є надзвичайно важливим. TypeScript, з його надійною системою статичної типізації, пропонує розробникам потужний набір інструментів для виявлення помилок на ранніх етапах циклу розробки. Серед його найскладніших особливостей є Type Guards, які дозволяють більш детально контролювати виведення типів у межах умовних блоків. Цей вичерпний посібник заглибиться у два ключові підходи до реалізації розширених type guards: Користувацькі функції-предикати та Валідація під час виконання. Ми дослідимо їхні нюанси, переваги, випадки використання та те, як ефективно використовувати їх для більш надійного та підтримуваного коду в глобальних командах розробки.

Розуміння TypeScript Type Guards

Перш ніж занурюватися в розширені техніки, давайте коротко повторимо, що таке type guards. У TypeScript, type guard - це особливий вид функції, яка повертає булеве значення і, що важливо, звужує тип змінної в межах області видимості. Це звуження базується на умові, перевіреній у type guard.

Найбільш поширені вбудовані type guards включають:

• typeof: Перевіряє примітивний тип значення (наприклад, "string", "number", "boolean", "undefined", "object", "function").
• instanceof: Перевіряє, чи є об'єкт екземпляром певного класу.
• in operator: Перевіряє, чи існує властивість в об'єкті.

Хоча вони неймовірно корисні, часто ми стикаємося з більш складними сценаріями, де ці базові guards виявляються недостатніми. Саме тут вступають в гру розширені type guards.

Користувацькі функції-предикати: Глибше занурення

Користувацькі функції-предикати - це визначені користувачем функції, які діють як type guards. Вони використовують спеціальний синтаксис типу повернення TypeScript: parameterName is Type. Коли така функція повертає true, TypeScript розуміє, що parameterName має тип Type в умовній області видимості.

Анатомія користувацької функції-предиката

Давайте розберемо сигнатуру користувацької функції-предиката:

            
function isMyCustomType(variable: any): variable is MyCustomType {
  // Implementation to check if 'variable' conforms to 'MyCustomType'
  return /* boolean indicating if it is MyCustomType */;
}

            

              
                Copy
              
            
          

• function isMyCustomType(...): Сама назва функції. Зазвичай прийнято позначати функції-предикати префіксом is для ясності.
• variable: any: Параметр, тип якого ми хочемо звузити. Часто він типізується як any або ширший union type, щоб дозволити перевіряти різні вхідні типи.
• variable is MyCustomType: Це магія. Він повідомляє TypeScript: "Якщо ця функція повертає true, то ви можете припустити, що variable має тип MyCustomType."

Практичні приклади користувацьких функцій-предикатів

Розглянемо сценарій, коли ми маємо справу з різними типами профілів користувачів, деякі з яких можуть мати права адміністратора.

Спочатку визначимо наші типи:

            
interface UserProfile {
  id: string;
  username: string;
}

interface AdminProfile extends UserProfile {
  role: 'admin';
  permissions: string[];
}

type Profile = UserProfile | AdminProfile;

            

              
                Copy
              
            
          

Тепер давайте створимо користувацьку функцію-предикат, щоб перевірити, чи даний Profile є AdminProfile:

            
function isAdminProfile(profile: Profile): profile is AdminProfile {
  return profile.role === 'admin';
}

            

              
                Copy
              
            
          

Ось як ми будемо це використовувати:

            
function displayUserProfile(profile: Profile) {
  console.log(`Username: ${profile.username}`);

  if (isAdminProfile(profile)) {
    // Inside this block, 'profile' is narrowed to AdminProfile
    console.log(`Role: ${profile.role}`);
    console.log(`Permissions: ${profile.permissions.join(', ')}`);
  } else {
    // Inside this block, 'profile' is narrowed to UserProfile (or the non-admin part of the union)
    console.log('This user has standard privileges.');
  }
}

const regularUser: UserProfile = { id: 'u1', username: 'alice' };
const adminUser: AdminProfile = { id: 'a1', username: 'bob', role: 'admin', permissions: ['read', 'write', 'delete'] };

displayUserProfile(regularUser);
// Output:
// Username: alice
// This user has standard privileges.

displayUserProfile(adminUser);
// Output:
// Username: bob
// Role: admin
// Permissions: read, write, delete

            

              
                Copy
              
            
          

У цьому прикладі isAdminProfile перевіряє наявність і значення властивості role. Якщо воно збігається з 'admin', TypeScript впевнено знає, що об'єкт profile має всі властивості AdminProfile всередині блоку if.

Переваги користувацьких функцій-предикатів:

• Безпека під час компіляції: Основна перевага полягає в тому, що TypeScript забезпечує безпеку типів під час компіляції. Помилки, пов'язані з неправильними припущеннями щодо типів, виявляються ще до запуску коду.
• Читабельність і підтримка: Функції-предикати з чіткими назвами роблять намір коду зрозумілим. Замість складних перевірок типів у рядку, ви маєте описовий виклик функції.
• Повторне використання: Функції-предикати можна повторно використовувати в різних частинах вашої програми, сприяючи принципу DRY (Don't Repeat Yourself).
• Інтеграція з системою типів TypeScript: Вони плавно інтегруються з існуючими визначеннями типів і можуть використовуватися з union types, discriminated unions і багатьом іншим.

Коли використовувати користувацькі функції-предикати:

• Коли вам потрібно перевірити наявність і конкретні значення властивостей, щоб розрізнити членів union type (особливо корисно для discriminated unions).
• Коли ви працюєте зі складними об'єктними структурами, де простих перевірок typeof або instanceof недостатньо.
• Коли ви хочете інкапсулювати логіку перевірки типів для кращої організації та повторного використання.

Валідація під час виконання: Подолання розриву

Хоча користувацькі функції-предикати чудово справляються з перевіркою типів під час компіляції, вони припускають, що дані *вже* відповідають очікуванням TypeScript. Однак у багатьох реальних програмах, особливо тих, які включають дані, отримані з зовнішніх джерел (API, вхідні дані користувача, бази даних, файли конфігурації), дані можуть не відповідати визначеним типам. Саме тут валідація під час виконання стає вирішальною.

Валідація під час виконання передбачає перевірку типу та структури даних під час виконання коду. Це особливо важливо при роботі з ненадійними або слабо типізованими джерелами даних. Статичні типи TypeScript надають креслення, але валідація під час виконання гарантує, що фактичні дані відповідають цьому кресленню під час їх обробки.

Чому валідація під час виконання?

Система типів TypeScript працює під час компіляції. Після того, як ваш код скомпільовано в JavaScript, інформація про типи в основному стирається. Якщо ви отримуєте дані з зовнішнього джерела (наприклад, відповідь JSON API), TypeScript не має можливості гарантувати, що вхідні дані фактично відповідатимуть вашим визначеним інтерфейсам або типам. Ви можете визначити інтерфейс для об'єкта User, але API може несподівано повернути об'єкт User з відсутнім полем email або неправильно типізованою властивістю age.

Валідація під час виконання діє як запобіжна сітка. Вона:

• Перевіряє зовнішні дані: Гарантує, що дані, отримані з API, вхідних даних користувача або баз даних, відповідають очікуваній структурі та типам.
• Запобігає помилкам під час виконання: Виявляє несподівані формати даних до того, як вони спричинять помилки нижче за течією (наприклад, спроба отримати доступ до властивості, яка не існує, або виконання операцій над несумісними типами).
• Підвищує надійність: Робить вашу програму більш стійкою до несподіваних змін даних.
• Допомагає в налагодженні: Надає чіткі повідомлення про помилки, коли валідація даних не вдається, допомагаючи швидко визначити проблеми.

Стратегії валідації під час виконання

Існує кілька способів реалізації валідації під час виконання в проектах JavaScript/TypeScript:

1. Ручні перевірки під час виконання

Це передбачає написання явних перевірок з використанням стандартних операторів JavaScript.

            
interface Product {
  id: string;
  name: string;
  price: number;
}

function isProduct(data: any): data is Product {
  if (typeof data !== 'object' || data === null) {
    return false;
  }
  const hasId = typeof (data as any).id === 'string';
  const hasName = typeof (data as any).name === 'string';
  const hasPrice = typeof (data as any).price === 'number';
  return hasId && hasName && hasPrice;
}

// Example usage with potentially untrusted data
const apiResponse = {
  id: 'p123',
  name: 'Global Gadget',
  price: 99.99,
  // might have extra properties or missing ones
};

if (isProduct(apiResponse)) {
  // TypeScript knows apiResponse is a Product here
  console.log(`Product: ${apiResponse.name}, Price: ${apiResponse.price}`);
} else {
  console.error('Invalid product data received.');
}

            

              
                Copy
              
            
          

Плюси: Відсутність зовнішніх залежностей, простий для простих типів.

Мінуси: Може стати дуже багатослівним і схильним до помилок для складних вкладених об'єктів або великих правил валідації. Ручне відтворення системи типів TypeScript є виснажливим.

2. Використання бібліотек валідації

Це найпоширеніший і рекомендований підхід для надійної валідації під час виконання. Бібліотеки, такі як Zod, Yup або io-ts, надають потужні системи валідації на основі схем.

Приклад з Zod

Zod - це популярна бібліотека оголошення та валідації схем TypeScript-first.

Спочатку встановіть Zod:

            
npm install zod
# or
yarn add zod

            

              
                Copy
              
            
          

Визначте схему Zod, яка відображає ваш інтерфейс TypeScript:

            
import { z } from 'zod';

// Define a Zod schema
const ProductSchema = z.object({
  id: z.string().uuid(), // Example: expecting a UUID string
  name: z.string().min(1, 'Product name cannot be empty'),
  price: z.number().positive('Price must be positive'),
  tags: z.array(z.string()).optional(), // Optional array of strings
});

// Infer the TypeScript type from the Zod schema
type Product = z.infer<typeof ProductSchema>;

// Function to process product data (e.g., from an API)
function processProductData(data: unknown): Product {
  try {
    const validatedProduct = ProductSchema.parse(data);
    // If parsing succeeds, validatedProduct is of type Product
    return validatedProduct;
  } catch (error) {
    console.error('Data validation failed:', error);
    // In a real app, you might throw an error or return a default/null value
    throw new Error('Invalid product data format.');
  }
}

// Example usage:
const rawApiResponse = {
  id: 'a1b2c3d4-e5f6-7890-1234-567890abcdef',
  name: 'Advanced Widget',
  price: 150.75,
  tags: ['electronics', 'new']
};

try {
  const product = processProductData(rawApiResponse);
  console.log(`Successfully processed: ${product.name}`);
} catch (e) {
  console.error('Failed to process product.');
}

const invalidApiResponse = {
  id: 'invalid-id',
  name: '',
  price: -10
};

try {
  const product = processProductData(invalidApiResponse);
  console.log(`Successfully processed: ${product.name}`);
} catch (e) {
  console.error('Failed to process product.');
}
// Expected output for invalid data:
// Data validation failed: [ZodError details...]
// Failed to process product.

            

              
                Copy
              
            
          

Плюси:

• Декларативні схеми: Коротко визначайте складні структури даних.
• Багаті правила валідації: Підтримує різні типи, перетворення та користувацьку логіку валідації.
• Виведення типів: Автоматично генерує типи TypeScript зі схем, забезпечуючи узгодженість.
• Звітування про помилки: Надає детальні, дієві повідомлення про помилки.
• Зменшує шаблонний код: Значно менше ручного кодування порівняно з ручними перевірками.

Мінуси:

• Вимагає додавання зовнішньої залежності.
• Невеликий час на навчання, щоб зрозуміти API бібліотеки.

3. Розділові об'єднання з перевірками під час виконання

Розділові об'єднання - це потужний шаблон TypeScript, де загальна властивість (дискримінант) визначає конкретний тип в об'єднанні. Наприклад, тип Shape може бути Circle або Square, які розрізняються за властивістю kind (наприклад, kind: 'circle' проти kind: 'square').

Хоча TypeScript забезпечує це під час компіляції, якщо дані надходять із зовнішнього джерела, вам все одно потрібно перевірити їх під час виконання.

            
interface Circle {
  kind: 'circle';
  radius: number;
}

interface Square {
  kind: 'square';
  sideLength: number;
}

type Shape = Circle | Square;

function getArea(shape: Shape): number {
  switch (shape.kind) {
    case 'circle':
      return Math.PI * shape.radius ** 2;
    case 'square':
      return shape.sideLength ** 2;
    // TypeScript ensures all cases are handled if type safety is maintained
  }
}

// Runtime validation for discriminated unions
function isShape(data: any): data is Shape {
  if (typeof data !== 'object' || data === null) {
    return false;
  }

  // Check for the discriminant property
  if (!('kind' in data) || (data.kind !== 'circle' && data.kind !== 'square')) {
    return false;
  }

  // Further validation based on the kind
  if (data.kind === 'circle') {
    return typeof data.radius === 'number' && data.radius > 0;
  } else if (data.kind === 'square') {
    return typeof data.sideLength === 'number' && data.sideLength > 0;
  }

  return false; // Should not be reached if kind is valid
}

// Example with potentially untrusted data
const apiData = {
  kind: 'circle',
  radius: 10,
};

if (isShape(apiData)) {
  // TypeScript knows apiData is a Shape here
  console.log(`Area: ${getArea(apiData)}`);
} else {
  console.error('Invalid shape data.');
}

            

              
                Copy
              
            
          

Використання бібліотеки валідації, такої як Zod, може значно спростити це. Методи discriminatedUnion або union Zod можуть визначати такі структури та елегантно виконувати валідацію під час виконання.

Функції-предикати проти валідації під час виконання: Коли що використовувати?

Це не ситуація або/або; скоріше, вони служать різним, але взаємодоповнюючим цілям:

Використовуйте користувацькі функції-предикати, коли:

• Внутрішня логіка: Ви працюєте в кодовій базі вашої програми, і ви впевнені в типах даних, які передаються між різними функціями або модулями.
• Гарантія під час компіляції: Ваша основна мета - використати статичний аналіз TypeScript для виявлення помилок під час розробки.
• Уточнення union types: Вам потрібно розрізнити членів union type на основі конкретних значень властивостей або умов, які TypeScript може вивести.
• Немає зовнішніх даних: Дані, що обробляються, надходять з вашого статично типізованого коду TypeScript.

Використовуйте валідацію під час виконання, коли:

• Зовнішні джерела даних: Робота з даними з API, вхідних даних користувача, локального сховища, баз даних або будь-якого джерела, де цілісність типу не може бути гарантована під час компіляції.
• Серіалізація/десеріалізація даних: Розбір JSON-рядків, даних форми або інших серіалізованих форматів.
• Обробка вхідних даних користувача: Валідація даних, надісланих користувачами через форми або інтерактивні елементи.
• Запобігання збоям під час виконання: Переконайтеся, що ваша програма не виходить з ладу через несподівані структури даних або значення у виробництві.
• Забезпечення бізнес-правил: Валідація даних на відповідність конкретним обмеженням бізнес-логіки (наприклад, ціна має бути додатною, формат електронної пошти має бути дійсним).

Поєднання їх для максимальної вигоди

Найефективніший підхід часто передбачає поєднання обох технік:

1. Спочатку валідація під час виконання: При отриманні даних із зовнішніх джерел використовуйте надійну бібліотеку валідації під час виконання (наприклад, Zod) для розбору та валідації даних. Це гарантує, що дані відповідають вашій очікуваній структурі та типам.
2. Виведення типів: Використовуйте можливості виведення типів бібліотек валідації (наприклад, z.infer<typeof schema>) для створення відповідних типів TypeScript.
3. Користувацькі функції-предикати для внутрішньої логіки: Після того, як дані перевірено та типізовано під час виконання, ви можете використовувати користувацькі функції-предикати у внутрішній логіці вашої програми для подальшого звуження типів членів union або виконання конкретних перевірок, де це необхідно. Ці предикати будуть працювати з даними, які вже пройшли валідацію під час виконання, що робить їх більш надійними.

Розглянемо приклад, коли ви отримуєте дані користувача з API. Ви б використали Zod для валідації вхідного JSON. Після валідації гарантовано, що об'єкт, що вийшов, матиме тип `User`. Якщо ваш тип `User` є об'єднанням (наприклад, `AdminUser | RegularUser`), ви можете використовувати користувацьку функцію-предикат `isAdminUser` на цьому вже перевіреному об'єкті `User` для виконання умовної логіки.

Глобальні міркування та найкращі практики

При роботі над глобальними проектами або з міжнародними командами використання розширених type guards і валідації під час виконання стає ще більш важливим:

• Узгодженість між регіонами: Переконайтеся, що формати даних (дати, числа, валюти) обробляються узгоджено, навіть якщо вони надходять з різних регіонів. Схеми валідації можуть забезпечити дотримання цих стандартів. Наприклад, валідація номерів телефонів або поштових індексів може вимагати різних шаблонів регулярних виразів залежно від цільового регіону, або більш загальної валідації, яка забезпечує формат рядка.
• Локалізація та інтернаціоналізація (i18n/l10n): Хоча це безпосередньо не пов'язано з перевіркою типів, структури даних, які ви визначаєте та перевіряєте, можуть потребувати розміщення перекладених рядків або конфігурацій для конкретного регіону. Ваші визначення типів повинні бути достатньо гнучкими.
• Співпраця команди: Чітко визначені типи та правила валідації служать універсальним контрактом для розробників у різних часових поясах і з різним досвідом. Вони зменшують непорозуміння та двозначності в обробці даних. Документування ваших схем валідації та функцій-предикатів є ключовим.
• Контракти API: Для мікросервісів або програм, які спілкуються через API, надійна валідація під час виконання на кордоні гарантує, що контракт API суворо дотримується як виробником, так і споживачем даних, незалежно від технологій, які використовуються в різних службах.
• Стратегії обробки помилок: Визначте узгоджені стратегії обробки помилок для невдалих валідацій. Це особливо важливо в розподілених системах, де помилки потрібно ефективно реєструвати та повідомляти в різних службах.

Розширені функції TypeScript, які доповнюють Type Guards

Окрім користувацьких функцій-предикатів, кілька інших функцій TypeScript покращують можливості type guard:

Розділові об'єднання

Як згадувалося, вони є фундаментальними для створення union types, які можна безпечно звужувати. Функції-предикати часто використовуються для перевірки властивості дискримінанта.

Умовні типи

Умовні типи дозволяють створювати типи, які залежать від інших типів. Їх можна використовувати в поєднанні з type guards, щоб виводити більш складні типи на основі результатів валідації.

            
type IsAdmin<T> = T extends { role: 'admin' } ? true : false;

type UserStatus = IsAdmin<AdminProfile>;
// UserStatus will be 'true'

            

              
                Copy
              
            
          

Відображені типи

Відображені типи дозволяють перетворювати існуючі типи. Ви потенційно можете використовувати їх для створення типів, які представляють валідовані поля, або для створення функцій валідації.

Висновок

Розширені type guards TypeScript, зокрема користувацькі функції-предикати та інтеграція з валідацією під час виконання, є незамінними інструментами для створення надійних, підтримуваних і масштабованих програм. Користувацькі функції-предикати дають розробникам змогу виражати складну логіку звуження типів у межах мережі безпеки TypeScript під час компіляції.

Однак для даних, що надходять із зовнішніх джерел, валідація під час виконання є не просто найкращою практикою – це необхідність. Бібліотеки, такі як Zod, Yup і io-ts, надають ефективні та декларативні способи забезпечити, щоб ваша програма обробляла лише дані, які відповідають її очікуваній формі та типам, запобігаючи помилкам під час виконання та підвищуючи загальну стабільність програми.

Розуміючи різні ролі та синергетичний потенціал як користувацьких функцій-предикатів, так і валідації під час виконання, розробники, особливо ті, хто працює в глобальному, різноманітному середовищі, можуть створювати більш надійне програмне забезпечення. Використовуйте ці розширені методи, щоб підняти вашу розробку TypeScript і створювати програми, які є такими ж стійкими, як і продуктивними.